PUT /manage/v2/forests/{id|name}/properties

Summary

Modify the configuration of the forest identified by {id|name}.

Response

Upon success, MarkLogic Server returns a status code 204 (No Content).

Required Privileges

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

Properties included in the payload replace the existing configuration of the same property, if any. All other properties remain unchanged. Replacement applies even where multiple property values are supported, such as replica forests. For example, if the request includes configuration for forest-replicas, all previously existing replica configuration is replaced. The operation is not additive.

Note: The properties described here are for XML payloads. In general they are the same for JSON, with the exception that, in JSON, failover-hosts and forest-replicas are expressed in singular form. For example, in JSON, failover-hosts is instead failover-host and the format is: "failover-host":["hostname"].

Note that adding or removing a replica forest to/from a master forest will take the master forest offline.

The structure of the modifiable properties is as follows:

database

The name of the database to which this forest is attached.

forest-name

The forest name.

enabled

Forest enabled status.

host

The primary host to which the forest is assigned.

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

updates-allowed

The kinds of updates that should be allowed for this forest.

availability

Availability of the forest data.

rebalancer-enable

Enable automatic rebalancing after configuration changes.

range

Range configuration for the range assignment policy.

This is a complex structure with the following children:

lower-bound

The lower bound of the range on the forest.

upper-bound

The upper bound of the range on the forest.

failover-enable

Enable assignment to a failover host if the primary host is down.

failover-hosts

A list of failover hosts for shared-disk failover.

This is a complex structure with the following children:

failover-host

A failover host.

forest-backups

Backups scheduled for this forest.

This is a complex structure with the following children:

forest-backup

A scheduled forest backup.

This is a complex structure with the following children:

backup-id

The backup ID.

backup-enabled

Whether or not a backup is enabled

backup-directory

The backup directory pathname.

backup-type

What type of backup is this.

backup-period

How often this backup should run (every n months, weeks, days, hours or minutes).

backup-month-day

The day of the month that this backup happens.

backup-days

The days that this backup happens.

This is a complex structure with the following children:

backup-day

A day that this backup occurs.

backup-start-date

The starting date (in MM/DD/YYYY notation) for a one-time backup

backup-start-time

The starting time (in 24:00 notation).

backup-timestamp

The date and time this backup was created.

forest-replicas

A list of replica forests, used for local-disk failover.

This is a complex structure with the following children:

forest-replica

The unique key of a forest.

This is a complex structure with the following children:

host

The primary host to which the forest is assigned.

replica-name

The name of a replica forest

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

database-replication

Database replication configuration.

This is a complex structure with the following children:

foreign-replicas

Foreign replicas of this database.

This is a complex structure with the following children:

foreign-replica

Foreign replica of this database.

This is a complex structure with the following children:

foreign-cluster-name

A foreign cluster ID.

foreign-database-name

A foreign database ID.

foreign-forest-name

A foreign forest ID.

foreign-master

Foreign replica of this database.

This is a complex structure with the following children:

foreign-cluster-name

A foreign cluster ID.

foreign-database-name

A foreign database ID.

foreign-forest-name

A foreign forest ID.

Example

$ cat ./forest-properties.xml
==> 
<forest-properties xmlns="http://marklogic.com/manage">
  <enabled>false</enabled>
</forest-properties>

$ cat ./forest-properties.json
==> 
{ "enabled": true }

$ curl --anyauth --user user:password -X PUT -d @./forest-properties.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8002/manage/v2/forests/example-1/properties

==> The enabled property of the forest named example-1 is set to false.
    All other properties are unchanged. MarkLogic Server responds with
    output similar to the following:

HTTP/1.1 204 No Content
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5